..Help
.Objects
|
File
 |
This multi-function object performs file IO. Modes include Data File, Memory Buffer, Media Reader and Wave Writer. |
Pins
| io |
letter |
name |
unit |
description |
| in |
L R | data input | auto | Left and right input data |
|---|
| s | seek | logic | seek to position trigger |
|---|
| w | write | write data trigger |
|---|
| m | move | move read trigger |
|---|
| sr | sample rate | Hertz | overrides the default sample rate |
|---|
| P | position | Percent | Position to seek to |
|---|
| out |
L R | auto | left and right data read from file |
|---|
Parameters
| name |
option |
key |
description |
| file mode |
Data File | read and write to a disk file using raw floating point numbers |
|---|
| Memory Buffer | read and write to shared memory using raw floating point numbers |
| Media Reader | reads the audio stream from a wide variety of formats |
| Wave Writer | write audio data to a 16 bit stereo WAV file |
| file name / ID | name of the file or identifier of the memory buffer |
|---|
| length | number of samples in the file |
|---|
| seek |
 |
when to seek to position P |
|---|
| sync | wait for seek events to complete |
|---|
| ± | P = -1 is start of file. P = +1 is end of file. |
| % | P = 0 is start of file. P = +1 is end of file. |
| write |
|
when to write LR input data to the file |
|---|
| move |
|
when move the read position by sr |
|---|
| auto rewind |
automatic rewind at end of file |
|---|
Notes
|
Outline
The position is updated every sample according to the settings
and values of the m, sr, s and P pins.
Data is read from the file at the new position.
The output data will not change if the position and file data have not changed.
The sequence of operation is seek write move read.
Seeking
Seek cancels move.
If seek is set to gate mode,
move is canceled while the gate is on and the position is constantly updated by the value at the P pin.
The P value may be interpreted as a percentage of the file length ranging from 0 to +1,
or as normalized phase with a range of -1 to +1.
Seeking from disk files is time consuming, even more so for compressed audio streams.
Excessive seeking results in sluggish response from the user interface.
ABox tries to reduce this by caching and limiting the number of disk reads in a sample frame.
The internal cache is 16KB, disk reads outside of the cache are limited to 16 per frame.
When seeking compressed audio streams, by default ABox will not wait for the seek to complete.
You may over-ride this by using seek sync.
Memory Buffer mode, on the other hand, does not suffer from seeking limits.
Writing
Write operations do not update the position.
The exception to this is the Wave Writer, described below.
Since writing happens before moving and reading,
the data you see at the output may not be the data you wrote at the input.
This can be used as a delay when auto rewind is on.
Moving
Setting m to gate mode will cause the position to be constantly updated while the gate is on.
This is useful for streaming configurations.
When moving, the position is updated by the value at the sr pin.
Some modes allow sr to be negative, causing the data to be read in reverse order.
If sr is not connected, it's value defaults to that of the source file.
Sample rate conversion is by duplicating samples.
This will result in distortion that increases with the amount of conversion.
A damper filter at the output can reduce this,
or use a third party sample rate converter to prepare the material before reading with ABox.
Configurations
Not all pins and options will be available in all modes.
For example, Media Reader is a read-only mode and you will not be able to write to the file.
All modes require a file name or ID.
Some modes allow the file length to be changed.
Doing so changes the length of all file objects using the same file.
You can not undo length changes.
The sections below describe each mode in more detail.
Data File and Memory Buffer
These two modes have similar configurations. You may seek, move, write and read as well as change the file length.
Data File uses physical disk storage and may be lengthened to 536 million samples, about 3 ½ hours at 44100Hz.
Memory Buffer uses system memory and may be lengthened to 262 thousand samples, about 6 seconds at 44100Hz.
Data files are bigger, but Memory buffers are far faster.
In both modes:
The default sample rate is 44100Hz.
Data may be shared between file objects and between instances of ABox.
The data format is always 4 byte IEEE floating point.
Changing the length of the file effects all objects using it.
You can not undo changes to the file length.
In Data File mode:
If the specified file does not exist, it will be created in the directory where the circuit was loaded from.
Files may used to pass data between dissimilar applications,
as long as they are opened in SHARE read write mode. SoftStep is one example.
When sharing files, care must be taken to allow for timing instabilities.
This will usually require that one application write several samples ahead of the other application.
In Memory Buffer mode:
There is a hard coded limit of 128 memory ID's.
Assigning more memory than available RAM will wake up the Windows Swap File and degrade system performance.
Media Reader
The media reader extracts the audio stream from any media format supported by Windows,
usually including WAV, MP3, MPEG, AVI, MOV, AU and AIFF.
You may have other formats installed on your system as well.
Media reader requires that DirectShow/ActiveMovie be installed on your system.
This is usually the case if you have Windows Media Player.
In this mode you may seek and move but not write or change the file length.
The default sample rate is read from the media file.
Seeking compressed audio streams is time-consuming.
By default, ABox will not wait for the seeking operation to complete,
sometimes resulting in dropped data from the file.
Use seek sync to force ABox to wait, at the risk of audio drop-outs in the rest of the circuit.
When reading from a video file, you can only seek to key frames.
Media files can not be played backwards,
sr values will be treated as positive numbers.
Wave Writer
The wave writer is designed to stream audio data to a WAV file.
The format is fixed at 44100Hz stereo 16 bits per sample.
In this mode you may write and rewind but not seek or move.
The file length and position will update automatically.
The wave file will always erase the file before play starts.
To help prevent accidental erasure,
ABox will first look at the Software Id inside the file.
If it does not say ABox, you will be asked if you really want to erase it.
Triggering the s pin will also erase the file.
Examples
Read the audio track from a media file.
Media Reader mode.
Set m as positive gate and leave it unconnected.
To replay, use auto rewind or connect to the s input.
|
Record the output of a circuit
Wave Writer mode.
Set w as positive gate and leave it unconnected.
Connect L and R inputs to source data.
Optionally, connect the A input to prevent clipping.
|
6 second delay
Memory Buffer mode.
Set file length to maximum.
Set w and m as positive gate and leave them unconnected.
Use auto rewind
|
1 hour delay
Data File mode.
You'll need 640MB of disk space to do this.
Set file length to 158,760,000 samples.
Set w and m as positive gate.
Use auto rewind
|
|
|